<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- creator-beautifier.qdoc -->
  <title>Beautifying Source Code | Qt Creator Manual</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt Creator Manual</a></td><td >Beautifying Source Code</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="index.html">Qt Creator Manual 4.11.1</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="creator-editor-refactoring.html" />
  <link rel="next" href="creator-editor-options.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="creator-editor-refactoring.html">Refactoring</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-editor-options.html">Configuring the Editor</a>
</p><p/>
<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Beautifying Source Code</h1>
<span class="subtitle"></span>
<!-- $$$creator-beautifier.html-description -->
<div class="descr"> <a name="details"></a>
<p>You can use the experimental Beautifier plugin to format your source code by using the following external tools:</p>
<ul>
<li><a href="http://astyle.sourceforge.net">Artistic Style</a></li>
<li><a href="http://clang.llvm.org/docs/ClangFormat.html">ClangFormat</a></li>
<li><a href="http://uncrustify.sourceforge.net">Uncrustify</a></li>
</ul>
<p>The Beautifier plugin parses the source code into component structures, such as assignment statements, if blocks, loops, and so on, and formats them as specified in the Beautifier options. You can use a predefined style or define your own style.</p>
<p>To use the Beautifier plugin:</p>
<ol class="1" type="1"><li>Download and install the tool to use for formatting source code:<ul>
<li><a href="http://sourceforge.net/projects/astyle/files/astyle">Artistic Style</a></li>
<li><a href="http://llvm.org/releases/download.html">ClangFormat</a></li>
<li><a href="http://sourceforge.net/projects/uncrustify/files/uncrustify">Uncrustify</a></li>
</ul>
<p>You might have to build the tools from sources for some platforms.</p>
</li>
<li>Select <b>Help</b> &gt; <b>About Plugins</b> &gt; <b>C++</b> &gt; <b>Beautifier</b> to enable the plugin.</li>
<li>Restart Qt Creator to be able to use the plugin.</li>
<li>Select <b>Tools</b> &gt; <b>Options</b> &gt; <b>Beautifier</b> to specify settings for beautifying files.</li>
<li>Select the <b>Enable auto format on file save</b> check box to automatically beautify files when you save them using the tool you select in the <b>Tool</b> field.<p class="centerAlign"><img src="images/qt-creator-beautifier-options-general.png" alt="" /></p></li>
<li>In the <b>Restrict to MIME types</b> field, define the MIME types of the files to beautify, separated by semicolons. Leave the field empty to apply the tool on all files.<p>This setting is applied only when automatically beautifying files on save. To restrict the MIME types when selecting the menu item to format the currently open file, specify this option in the tool-specific tab.</p>
</li>
<li>Select the <b>Restrict to files contained in the current project</b> check box to only beautify files that belong to the current project.</li>
<li>Select <b>Artistic Style</b>, <b>Clang Format</b>, or <b>Uncrustify</b> to specify settings for the tool you want to use.<p class="centerAlign"><img src="images/beautifier_options.png" alt="" /></p></li>
<li>In the <b>Configuration</b> group, specify the path to the tool executable in the <b>Artistic Style command</b>, <b>Clang Format command</b>, or <b>Uncrustify command</b> field.</li>
<li>In the <b>Restrict to MIME types</b> field, define the MIME types of the files to beautify. This setting is applied when you select the menu item to format the currently open file.</li>
<li>In the <b>Options</b> group, select the configuration file that defines the style to use in the source files. If you select several options, they are applied from top down. The available options depend on the tool.<ul>
<li>Select the <b>Use file defined in project files</b> option to use the configuration file defined in the qmake DISTFILES variable as the configuration file for the selected tool. This option is available for Artistic Style and Uncrustify.</li>
<li>Select the <b>Use specific config file</b> option to use the specified file as the configuration file for the selected tool. This option is available for Artistic Style and Uncrustify.</li>
<li>Select the <b>Use file in $HOME</b> option to use the specified file in the user's home directory as the configuration file for the selected tool. This option is available for Artistic Style and Uncrustify.</li>
<li>For Clang Format, you can use a predefined style, by selecting the <b>Use predefined style</b> radio button, and then selecting the style to use from the list of available styles.<p>Select <b>File</b> to load the style configuration from the <code>.clang-format</code> or <code>_clang-format</code> file located in the same directory as the source file or in one of its parent directories.</p>
<p>To specify a fallback style to use if the style configuration file is not available, use the <b>Fallback style</b> combo box. Select <b>Default</b> to use the default style. Select <b>None</b> to skip formatting.</p>
</li>
<li>Select the <b>Use customized style</b> option, and then <b>Add</b> to define your own style.<p>Define code formatting in the <b>Add Configuration</b> dialog. It provides syntax highlighting, auto-completion, and context-sensitive help. For these features, you must have the tool installed.</p>
<p class="centerAlign"><img src="images/beautifier_editor.png" alt="" /></p></li>
</ul>
</li>
<li>Select <b>Tools</b> &gt; <b>Options</b> &gt; <b>Beautifier</b> &gt; <b>Artistic Style</b>, <b>ClangFormat</b>, or <b>Uncrustify</b> &gt; <b>Format Current File</b> to format the currently open file.<p>You can <a href="creator-keyboard-shortcuts.html">create keyboard shortcuts</a> for the functions.</p>
</li>
</ol>
<p>In addition to the <b>Format Current File</b> command, ClangFormat and Uncrustify provide additional commands. ClangFormat provides the <b>Format at Cursor</b> command. If you select it when no text is selected, the syntactic entity under the cursor is formatted. The <b>Disable Formatting for Selected Text</b> command wraps selected lines within <code>// clang-format off</code> and <code>// clang-format on</code>. Uncrustify provides the <b>Format Selected Text</b> command. If you select it when no text is selected, the whole file is formatted by default. To disable this behavior, deselect the <b>Format entire file if no text was selected</b> check box.</p>
</div>
<!-- @@@creator-beautifier.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="creator-editor-refactoring.html">Refactoring</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-editor-options.html">Configuring the Editor</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
